Ambient Code Platform

Kubernetes-native AI automation platform that orchestrates agentic sessions through containerized microservices. Built with Go (backend, operator), NextJS + Shadcn (frontend), Python (runner), and Kubernetes CRDs.

Technical artifacts still use "vteam" for backward compatibility.

Structure

• components/backend/ - Go REST API (Gin), manages K8s Custom Resources with multi-tenant project isolation
• components/frontend/ - NextJS web UI for session management and monitoring
• components/operator/ - Go Kubernetes controller, watches CRDs and creates Jobs
• components/runners/ambient-runner/ - Python runner executing Claude Code CLI in Job pods
• components/ambient-cli/ - Go CLI (acpctl), manages agentic sessions from the command line
• components/public-api/ - Stateless HTTP gateway, proxies to backend (no direct K8s access)
• components/manifests/ - Kustomize-based deployment manifests and overlays
• e2e/ - Cypress end-to-end tests
• docs/ - Astro Starlight documentation site

Key Files

• CRD definitions: components/manifests/base/crds/agenticsessions-crd.yaml, projectsettings-crd.yaml
• Session lifecycle: components/backend/handlers/sessions.go, components/operator/internal/handlers/sessions.go
• Auth & RBAC middleware: components/backend/handlers/middleware.go
• K8s client init: components/operator/internal/config/config.go
• Runner entry point: components/runners/ambient-runner/main.py
• Route registration: components/backend/routes.go
• Frontend API layer: components/frontend/src/services/api/, src/services/queries/

Session Flow

User Creates Session → Backend Creates CR → Operator Spawns Job →
Pod Runs Claude CLI → Results Stored in CR → UI Displays Progress

Commands

make build-all                # Build all container images
make deploy                   # Deploy to cluster
make test                     # Run tests
make lint                     # Lint code
make kind-up                  # Start local Kind cluster
make test-e2e-local           # Run E2E tests against Kind

Per-Component

# Backend / Operator (Go)
cd components/backend && gofmt -l . && go vet ./... && golangci-lint run
cd components/operator && gofmt -l . && go vet ./... && golangci-lint run

# Frontend
cd components/frontend && npm run build  # Must pass with 0 errors, 0 warnings

# Runner (Python)
cd components/runners/ambient-runner && uv venv && uv pip install -e .

# Docs
cd docs && npm run dev  # http://localhost:4321

Critical Context

• User token auth required: All user-facing API ops use GetK8sClientsForRequest(c), never the backend service account
• OwnerReferences on all child resources: Jobs, Secrets, PVCs must have controller owner refs
• No panic() in production: Return explicit fmt.Errorf with context
• No any types in frontend: Use proper types, unknown, or generic constraints
• Conventional commits: Squashed on merge to main

Pre-commit Hooks

The project uses the pre-commit framework to run linters locally before every commit. Configuration lives in .pre-commit-config.yaml.

Install

make setup-hooks

What Runs

On every git commit:

On every git push:

Run Manually

make lint                                    # All hooks, all files
pre-commit run gofmt-check --all-files       # Single hook
pre-commit run --files path/to/file.go       # Single file

Skip Hooks

git commit --no-verify    # Skip pre-commit hooks
git push --no-verify      # Skip pre-push hooks

Notes

• Go and ESLint wrappers (scripts/pre-commit/) skip gracefully if the toolchain is not installed
• tsc --noEmit and npm run build are not included (slow; CI gates on them)
• Branch/push protection scripts remain in scripts/git-hooks/ and are invoked by pre-commit

More Info

See BOOKMARKS.md for architecture decisions, development context, code patterns, and component-specific guides.

Claude Code Review

Summary

This PR adds LDAP-backed user and group autocomplete to the workspace sharing flow. The feature is well-scoped, optional-by-default (graceful degradation when unconfigured), and includes solid test coverage. The LDAP client uses proper filter escaping and input sanitization. A few issues need attention before merge: all three new handlers use the wrong variable for the auth nil check (deviating from the mandatory project pattern), and the frontend builds a custom combobox from scratch when a Shadcn equivalent exists.

Issues by Severity

Blocker Issues

None.

Critical Issues

1. Auth nil check uses wrong client variable in all 3 handlers

Files: components/backend/handlers/ldap.go lines 69-70, 99-100, 129-130

All three handlers discard reqK8s with _ and check k8sDyn (the dynamic client) for nil:

_, k8sDyn := GetK8sClientsForRequest(c)
if k8sDyn == nil {

The documented mandatory pattern across the entire codebase (backend-development.md, k8s-client-usage.md, security-standards.md) is to check the typed K8s client (reqK8s):

reqK8s, _ := GetK8sClientsForRequest(c)
if reqK8s == nil {
    c.JSON(http.StatusUnauthorized, gin.H{"error": "Invalid or missing token"})
    c.Abort()
    return
}

While functionally equivalent today (both return nil together), this breaks the established convention, hides the unused reqK8s, and creates a maintenance hazard if GetK8sClientsForRequest behavior ever diverges. All three handlers (SearchLDAPUsers, SearchLDAPGroups, GetLDAPUser) need this fix.

Violates: backend-development.md Critical Rules - Authentication and Authorization; k8s-client-usage.md Pattern 1.

Major Issues

2. Custom combobox dropdown built from scratch instead of Shadcn Command

File: components/frontend/src/components/workspace-sections/_components/ldap-autocomplete.tsx

The component renders a bare <ul> styled with Shadcn design tokens to simulate a dropdown. Shadcn ships a Command component (built on CMDK) designed exactly for async-populated autocomplete patterns, already available in the project's UI kit.

Per frontend-development.md Shadcn UI Components Only rule: FORBIDDEN: Creating custom UI components from scratch for buttons, inputs, dialogs, etc.

The Shadcn Popover + Command + CommandInput + CommandList pattern is the correct implementation path. It also provides accessibility (ARIA roles, keyboard navigation) for free rather than re-implementing manually.

3. New LDAP connection opened per search, no pooling

File: components/backend/ldap/client.go - SearchUsers, SearchGroups, GetUser

Each search dials a fresh TCP+TLS connection and closes it immediately via defer conn.Close(). Every cache miss creates a new LDAP connection. A user typing 5 characters generates up to 4 cold-connection searches (after the first 2-char trigger). At scale this adds meaningful latency and load on the LDAP server. Recommend persisting a connection with reconnect-on-error, or at minimum documenting this as a known limitation.

4. LDAP_GROUP_BASE_DN env var not mapped in deployment manifest

File: components/manifests/base/backend-deployment.yaml

main.go reads os.Getenv("LDAP_GROUP_BASE_DN") but the deployment manifest only maps LDAP_URL, LDAP_BASE_DN, and LDAP_SKIP_TLS_VERIFY from the ldap-config ConfigMap. Operators who need a non-default group base DN cannot configure it without manually patching the manifest.

Minor Issues

5. k8sDyn obtained but never used for K8s operations

File: components/backend/handlers/ldap.go lines 69, 99, 129

The dynamic client is obtained and only checked for nil, never used for actual K8s operations. Once Critical issue 1 is fixed, simplify to reqK8s, _ := GetK8sClientsForRequest(c).

6. Component exceeds 200-line guideline

File: components/frontend/src/components/workspace-sections/_components/ldap-autocomplete.tsx (252 lines)

frontend-development.md sets a 200-line limit. Much of the excess comes from duplicated render blocks for user vs group modes. Extracting a shared ResultItem sub-component would reduce size and eliminate the duplication.

7. Trivial JSDoc comments on self-evident functions

Files: components/frontend/src/services/api/ldap.ts, components/frontend/src/services/queries/use-ldap.ts

Comments like /** Search LDAP users by query (min 2 chars) */ add no information beyond the function name. Per CLAUDE.md: only add comments where logic is not self-evident.

Positive Highlights

• Injection prevention is solid: sanitizeQuery strips newlines and carriage returns to block log injection, and goldap.EscapeFilter() is applied to every query before it enters an LDAP filter. The %q format verb in log lines ensures special chars are Go-quoted, not literal.
• TLS hardened correctly: MinVersion: tls.VersionTLS12 is set, and InsecureSkipVerify has a proper nolint:gosec annotation noting it is dev-only and env-var-controlled.
• Cache is thread-safe: sync.Map is the right primitive for concurrent read-heavy access, and TTL expiry is correctly lazy-evaluated on read.
• Comprehensive unit tests: 9 test cases cover filter generation (special chars, multi-word, asterisk), DN parsing, query sanitization (newline stripping, truncation), cache TTL expiry, and short-query early-exit. Exactly the coverage this new LDAP package warrants.
• React Query hooks follow the pattern precisely: enabled: query.length >= 2, staleTime set, hierarchical key factory (ldapKeys.userSearch(query)) correctly includes the query in the cache key with no collision risk.
• Graceful degradation is well-implemented: optional: true on all ConfigMap refs, LDAPClient == nil guards in every handler, frontend falls back silently to no suggestions.
• UX improvement in sharing-section.tsx: Clearing subjectName on subject-type switch prevents stale values carrying over between user/group modes.

Recommendations

1. (Critical) Fix all three handlers: reqK8s, _ := GetK8sClientsForRequest(c) and check reqK8s == nil.
2. (Major) Replace the custom <ul> dropdown with Shadcn Popover + Command + CommandList.
3. (Major) Add LDAP_GROUP_BASE_DN to backend-deployment.yaml env mappings and ConfigMap specs.
4. (Major) Document the per-request connection model as a known limitation, or add connection pooling.
5. (Minor) Remove trivial JSDoc comments from ldap.ts and use-ldap.ts.
6. (Minor) Extract a shared ResultItem component to bring ldap-autocomplete.tsx under 200 lines.

Disabling TLS verification in production is intentional for now until we switch to an authenticated LDAP server. The risk of doing this is minimal since the cluster is for authenticated users only and the risk of MITM is low.

Walkthrough

Adds LDAP integration: backend LDAP client with caching and search, HTTP handlers, frontend proxy routes and React Query hooks, an LDAP autocomplete React component integrated into workspace sharing behind a feature flag, and Kubernetes ConfigMaps plus deployment env vars for LDAP configuration.

Changes

Sequence Diagram(s)

sequenceDiagram
    participant User as User
    participant UI as LDAPAutocomplete
    participant ReactQuery as React Query
    participant Frontend as Frontend Route
    participant Backend as Backend Handler
    participant Client as LDAP Client
    participant LDAP as LDAP Server

    User->>UI: Type query
    UI->>UI: Debounce 300ms
    UI->>ReactQuery: request search(query)
    ReactQuery->>ReactQuery: check cache
    alt cache hit
        ReactQuery-->>UI: return cached results
    else
        ReactQuery->>Frontend: GET /api/ldap/...?q=query
        Frontend->>Backend: forward request + headers
        Backend->>Backend: auth & validate query
        Backend->>Client: SearchUsers/SearchGroups(query)
        Client->>Client: check local cache
        alt cache hit
            Client-->>Backend: return cached entries
        else
            Client->>LDAP: LDAP search with filter
            LDAP-->>Client: entries
            Client->>Client: parse & cache results
            Client-->>Backend: return entries
        end
        Backend-->>Frontend: 200 + JSON
        Frontend-->>ReactQuery: 200 + JSON
        ReactQuery-->>UI: results
    end
    UI->>User: render suggestions

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~50 minutes

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

test connection

Ambient Code Platform

Kubernetes-native AI automation platform that orchestrates agentic sessions through containerized microservices. Built with Go (backend, operator), NextJS + Shadcn (frontend), Python (runner), and Kubernetes CRDs.

Technical artifacts still use "vteam" for backward compatibility.

Structure

• components/backend/ - Go REST API (Gin), manages K8s Custom Resources with multi-tenant project isolation
• components/frontend/ - NextJS web UI for session management and monitoring
• components/operator/ - Go Kubernetes controller, watches CRDs and creates Jobs
• components/runners/ambient-runner/ - Python runner executing Claude Code CLI in Job pods
• components/ambient-cli/ - Go CLI (acpctl), manages agentic sessions from the command line
• components/public-api/ - Stateless HTTP gateway, proxies to backend (no direct K8s access)
• components/manifests/ - Kustomize-based deployment manifests and overlays
• e2e/ - Cypress end-to-end tests
• docs/ - Astro Starlight documentation site

Key Files

• CRD definitions: components/manifests/base/crds/agenticsessions-crd.yaml, projectsettings-crd.yaml
• Session lifecycle: components/backend/handlers/sessions.go, components/operator/internal/handlers/sessions.go
• Auth & RBAC middleware: components/backend/handlers/middleware.go
• K8s client init: components/operator/internal/config/config.go
• Runner entry point: components/runners/ambient-runner/main.py
• Route registration: components/backend/routes.go
• Frontend API layer: components/frontend/src/services/api/, src/services/queries/

Session Flow

User Creates Session → Backend Creates CR → Operator Spawns Job →
Pod Runs Claude CLI → Results Stored in CR → UI Displays Progress

Commands

make build-all                # Build all container images
make deploy                   # Deploy to cluster
make test                     # Run tests
make lint                     # Lint code
make kind-up                  # Start local Kind cluster
make test-e2e-local           # Run E2E tests against Kind

Per-Component

# Backend / Operator (Go)
cd components/backend && gofmt -l . && go vet ./... && golangci-lint run
cd components/operator && gofmt -l . && go vet ./... && golangci-lint run

# Frontend
cd components/frontend && npm run build  # Must pass with 0 errors, 0 warnings

# Runner (Python)
cd components/runners/ambient-runner && uv venv && uv pip install -e .

# Docs
cd docs && npm run dev  # http://localhost:4321

Critical Context

• User token auth required: All user-facing API ops use GetK8sClientsForRequest(c), never the backend service account
• OwnerReferences on all child resources: Jobs, Secrets, PVCs must have controller owner refs
• No panic() in production: Return explicit fmt.Errorf with context
• No any types in frontend: Use proper types, unknown, or generic constraints
• Conventional commits: Squashed on merge to main

Pre-commit Hooks

The project uses the pre-commit framework to run linters locally before every commit. Configuration lives in .pre-commit-config.yaml.

Install

make setup-hooks

What Runs

On every git commit:

On every git push:

Run Manually

make lint                                    # All hooks, all files
pre-commit run gofmt-check --all-files       # Single hook
pre-commit run --files path/to/file.go       # Single file

Skip Hooks

git commit --no-verify    # Skip pre-commit hooks
git push --no-verify      # Skip pre-push hooks

Notes

• Go and ESLint wrappers (scripts/pre-commit/) skip gracefully if the toolchain is not installed
• tsc --noEmit and npm run build are not included (slow; CI gates on them)
• Branch/push protection scripts remain in scripts/git-hooks/ and are invoked by pre-commit

Testing

• Frontend unit tests: cd components/frontend && npx vitest run --coverage (466 tests, ~74% coverage). See components/frontend/README.md.
• E2E tests: cd e2e && npx cypress run --browser chrome (58 tests, mock SDK). See e2e/README.md.
• Runner tests: cd components/runners/ambient-runner && python -m pytest tests/
• Backend tests: cd components/backend && make test. See components/backend/TEST_GUIDE.md.

More Info

See BOOKMARKS.md for architecture decisions, development context, code patterns, and component-specific guides.

Review posted - see full analysis below in a follow-up comment.

CRITICAL: TLS verification disabled in production LDAP config (components/manifests/overlays/production/ldap-config.yaml:9 sets LDAP_SKIP_TLS_VERIFY to true). This exposes the ldaps:// connection to MITM attacks. Fix: set to false or remove the key in production overlay. The dev overlays can keep it. Standard: security-standards.md.

MAJOR: Custom autocomplete dropdown instead of Shadcn Combobox pattern. File: ldap-autocomplete.tsx. The dropdown uses raw ul/li elements with hand-rolled focus, keyboard navigation, and click-outside logic. Shadcn ships Command + Popover Combobox for exactly this use case. Standard violated: frontend-development.md Shadcn UI Components Only rule (FORBIDDEN: Creating custom UI components from scratch). Fix: replace with Popover, PopoverContent, PopoverTrigger, Command, CommandInput, CommandList, CommandItem, CommandEmpty. Bonus: the component is also 252 lines (limit is 200); switching to Shadcn Combobox will bring it under the limit. Standard: frontend-development.md.

MINOR issues (4): (1) Inconsistent HTTP status codes: SearchLDAPUsers/Groups return 503 but GetLDAPUser returns 500 for the same failure class — standardise on 503 (handlers/ldap.go:104 vs :164). (2) Hardcoded org domain fallback in NewClient: the fallback ou=managedGroups,dc=redhat,dc=com bakes a Red Hat-specific domain into a generic library — log a warning instead (ldap/client.go:249). (3) useLDAPUser hook and ldapApi.getUser are exported but not used anywhere in this PR — remove or document intent. (4) autocomplete component has no error state: the useEffect checks isLoading/hasResults but not error, so LDAP query failures silently close the dropdown — render a brief message when error is set.

POSITIVE HIGHLIGHTS: (1) Excellent LDAP injection prevention — goldap.EscapeFilter() used in all filter builders, sanitizeQuery() strips newlines, %q format verb throughout error logs. (2) Auth pattern correct throughout — every handler uses GetK8sClientsForRequest(c) with 401 on nil, per k8s-client-usage.md. (3) Graceful degradation — LDAP optional (LDAP_URL env gated), Unleash-flag gated in frontend, sharing form falls back to plain Input. (4) Cache TTL consistent end-to-end — backend 5 min, frontend staleTime 5 min. (5) Solid test coverage — filters, TTL expiry, sanitizeQuery, ParseGitHubUsername, short-query cases all tested. (6) LDAPResultSizeLimitExceeded treated as non-fatal partial result — correct for autocomplete. (7) Makefile Unleash password fix replaces hardcoded default with kubectl secret lookup.

Claude Code Review

Summary

This PR adds LDAP-backed autocomplete for user and group selection in the workspace sharing dialog. The implementation is well-scoped: a new Go LDAP package with in-memory caching, three authenticated API endpoints, Next.js proxy routes, and a React Query-powered frontend. Graceful degradation (LDAP optional, feature-flagged) is handled correctly throughout. However, a production manifest with TLS verification disabled and a frontend component that bypasses Shadcn UI conventions need to be addressed.

Issues by Severity

Blocker Issues

None

Critical Issues

1. Production manifest ships with TLS verification disabled

components/manifests/overlays/production/ldap-config.yaml sets LDAP_SKIP_TLS_VERIFY: "true". This disables X.509 certificate verification on the LDAPS connection, making production traffic vulnerable to MITM attacks. The nolint comment in ldap/client.go already calls this out as dev-only:

InsecureSkipVerify: c.skipTLSVerify, //nolint:gosec // controlled by LDAP_SKIP_TLS_VERIFY env var for dev

Setting it "true" in kind and local-dev is fine. In production it must be "false" or the key omitted entirely (Go zero value for bool is false).

Violates: security-standards.md — no credential/transport bypass in production.

2. LDAPAutocomplete builds a custom dropdown instead of Shadcn Command/Combobox

ldap-autocomplete.tsx renders a hand-rolled <ul> dropdown with manual keyboard navigation and highlight tracking. Shadcn ships a Command component (built on cmdk) that provides exactly this pattern. Frontend standards are zero-tolerance here:

FORBIDDEN: Creating custom UI components from scratch for buttons, inputs, dialogs, etc.
REQUIRED: Use @/components/ui/* components

The correct approach is Popover + Command + CommandInput + CommandList + CommandItem, which also provides built-in keyboard navigation, ARIA semantics, and theming. The component is also 252 lines, exceeding the 200-line pre-commit limit.

Violates: frontend-development.md — Shadcn UI components only (zero tolerance).

Major Issues

3. In-memory cache has no active eviction

ldap/client.go — the sync.Map-based cache uses lazy expiry: stale entries are only removed when cacheGet is called for that exact key again. Entries for queries never repeated stay in memory indefinitely. In a long-running backend serving many distinct autocomplete queries, the cache will grow without bound. Recommend a periodic sweeper in NewClient:

go func() {
    ticker := time.NewTicker(c.cacheTTL)
    defer ticker.Stop()
    for range ticker.C {
        c.cache.Range(func(key, val any) bool {
            if e, ok := val.(cacheEntry); ok && time.Now().After(e.expiresAt) {
                c.cache.Delete(key)
            }
            return true
        })
    }
}()

Violates: backend-development.md — performance — unbounded list operations.

Minor Issues

4. useWorkspaceFlag isLoading not handled — brief UI flash

sharing-section.tsx:37 only destructures enabled from useWorkspaceFlag. While the flag is loading, ldapEnabled is false, so the plain <Input> renders first and then switches to <LDAPAutocomplete> once resolved. Destructure and use isLoading to disable the input while loading.

Violates: frontend-development.md — loading states must be handled.

5. LDAP startup log reveals deployment configuration at INFO level

main.go:144 logs the full LDAP URL, base DNs, and TLS skip setting at INFO on startup. These are not secrets, but verbose operational detail. A simple log.Println("LDAP client initialized") is preferable.

Positive Highlights

• Excellent input sanitization: sanitizeQuery strips newlines (preventing log injection) and truncates to maxQueryLength. goldap.EscapeFilter() is used correctly throughout all filter builders — no LDAP injection risk.
• Graceful degradation is well-implemented: LDAPClient == nil returns empty arrays (not errors) for search, and the feature flag gates the UI correctly. No panics if LDAP is unreachable.
• User token auth correctly enforced on all three LDAP endpoints: GetK8sClientsForRequest is called in every handler with a 401 return on failure — no service account fallback.
• React Query hooks follow project patterns exactly: ldapKeys factory, enabled guard on minimum query length, staleTime matching the backend 5-minute cache TTL, clean api/ vs queries/ separation.
• Strong test coverage for filter logic: client_test.go covers filter building, GitHub username parsing, cache TTL behaviour, and sanitization edge cases.
• Kubernetes configuration is clean: all LDAP env vars use optional: true, so existing deployments without the ConfigMap are unaffected.

Recommendations

1. [Critical] Set LDAP_SKIP_TLS_VERIFY: "false" or remove the key from production/ldap-config.yaml.
2. [Critical] Replace the hand-rolled dropdown in ldap-autocomplete.tsx with Shadcn Popover + Command + CommandList + CommandItem.
3. [Major] Add a periodic cache sweeper in ldap/client.go NewClient to evict expired entries.
4. [Minor] Destructure and use isLoading from useWorkspaceFlag in sharing-section.tsx.
5. [Minor] Reduce the LDAP startup log verbosity in main.go.

Review generated by Claude Code using repository standards from .claude/context/ and .claude/patterns/.

Review Queue — Blockers Found

This comment is auto-generated by the Review Queue workflow and will be updated when the PR changes.